<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Extending the B0-based remote API</title>
<link rel="stylesheet" type="text/css" href="../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../index.html" TARGET="_top"><img src="images/homeImg.png"></a></p>



<h1>Extending the B0-based remote API</h1>

<p class=warningBox>The B&Oslash;-based remote API should not be mixed-up with the <a href="legacyRemoteApiOverview.htm">legacy remote API</a> (or simply <em>remote API</em>), which is an older version of the remote API that is less flexible, and more difficult to extend.</p>

<p>You basically have two options, if you wish to use API commands that are not exposed by the B0-based remote API:</p>

<li><a href="#genericFunction">You can use the generic function simxCallScriptFunction</a></li>
<li><a href="#extending">You can extend the B0-based remote API</a></li>

<br>
<br>

<p><a name="genericFunction" id="genericFunction"></a><strong>Using the generic function simxCallScriptFunction</strong>: instead of extending the functions that the B0-based remote API offers, one can  use the generic B0-based remote API function <a href="b0RemoteApi-cpp.htm#simxCallScriptFunction">simxCallScriptFunction</a>: this will call a CoppeliaSim script function, which can then execute any type of operation locally, then return data. For instance:</p>

<pre class=lightRedBox>
function myFunctionName(args)
    for i=1,#args,1 do
        print('Argument '..i..' is :')
        print(args[i])
        print('')
    end
    return 'Hello to you too!',42 -- return a string and a number
end</pre>

<br>

<p>The B0-based remote API client application would then call above script function in following manner (e.g. via a Python script):</p>

<pre class=lightPurpleBox>
import b0RemoteApi

with b0RemoteApi.RemoteApiClient('b0RemoteApi_pythonClient','b0RemoteApi') as client:    
    args=['Hello World!',[1,2,3],59]
    ret=client.simxCallScriptFunction('myFunctionName@objectPath','sim.scripttype_childscript',args,client.simxServiceCall())
    print(ret)</pre>

<br>

<p>Make sure that the script, where you are trying to call a function, is initialized: trying to call a function in a <a href="simulationScripts.htm">simulation script</a>, while simulation is not running will not work.</p>

<br>

<p><a name="extending" id="extending"></a><strong>Extending the B0-based remote API</strong>: there are 4 simple steps involved:</p>

<li>Add your function as the end of file <em>programming/remoteApiBindings/b0-based/generate/simxFunctions.xml</em></li>
<li>Run following: <em>python generate.py --gen-simx-all --xml-file simxFunctions.xml ./generated</em></li>
<li>As a result of previous step, <em>/generated</em> will contain the client-side B0-based remote API code, as well as the generated documentation. Copy those files into place.
   </li>
<li>Finally, add the server-side counterpart to your new function at the beginning of file <em>lua/b0RemoteApiServer.lua</em></li>




<br>
<br>
 </tr>
 <tr>
   <td > 
 </tr>
</table> 
</div>  
  
  
</body>

</html>
